筆記目錄

雲翼的技術隨筆

主題

註：此版本由 AI 自動翻譯與摘要，不保證內容絕對精確
原始筆記

使用 Docker Compose 架設與配置 Nginx ​

TLDR ​

  • Nginx 設定檔由 Main、Events、HTTP Context 組成，建議將自定義設定放在 /etc/nginx/conf.d/ 目錄下。
  • location 匹配優先級：精確匹配 (=) > 前綴強匹配 (^~) > 正規表示式 (~, ~*) > 普通前綴匹配 > 通用匹配 (/)。
  • proxy_pass 是否包含結尾斜線（Trailing Slash）會影響路徑轉發行為。
  • 建議將 map 指令集中在獨立的 maps.conf 檔案中，避免因檔名載入順序導致變數覆蓋。
  • 使用 Docker 掛載設定檔時，建議加上 :ro（唯讀）以保護設定檔，但 log 目錄需保留寫入權限。
  • 修改設定後，請務必先執行 nginx -t 檢查語法，再使用 nginx -s reload 重新載入，避免服務中斷。
  • 若需使用環境變數動態配置 Nginx，可利用官方映像的 Template 功能，但修改變數後必須重啟容器。

Nginx 架構與設定階層 ​

Nginx 設定檔由多個 Context 組成，每個區塊對應不同層級的設定：

  • Main Context：最外層，定義全域參數（如 worker 數量、使用者權限）。
  • Events Context：定義連線處理參數（如 worker_connections）。
  • HTTP Context：定義 HTTP 伺服器全域設定（如 MIME 類型、log 格式）。

Location 區塊匹配規則 ​

什麼情況下會遇到這個問題：當需要定義複雜的路由規則，且不確定請求會被哪一個 location 區塊處理時。

Location 支援多種匹配修飾符，優先級如下：

  1. 精確匹配 =：完全相同才匹配（最高優先）。
  2. 前綴強匹配 ^~：前綴匹配成功後，停止搜尋正規表示式。
  3. 正規表示式（區分大小寫） ~：按定義順序，先匹配先使用。
  4. 正規表示式（不區分大小寫） ~*：按定義順序，先匹配先使用。
  5. 普通前綴匹配：最長的優先。
  6. 通用匹配 /：預設規則（最低優先）。

WARNING

若同時定義 location /test 和 location ^~ /test，Nginx 會因為規則衝突而報錯。

Proxy Pass 與路徑處理 ​

什麼情況下會遇到這個問題：當反向代理轉發請求時，發現後端收到的路徑與預期不符。

proxy_pass 的 URI 是否包含 trailing slash（結尾斜線）會影響轉發行為：

  • 無 trailing slash：完整轉發。
    • proxy_pass http://backend;
    • 請求 /app/test -> 轉發至 http://backend/app/test
  • 有 trailing slash：進行路徑替換。
    • proxy_pass http://backend/;
    • 請求 /app/test -> 轉發至 http://backend/test

設定檔管理建議 ​

檔案結構與 Map 共享 ​

什麼情況下會遇到這個問題：當專案規模變大，設定檔分散在多個檔案，導致變數定義衝突時。

在 http 區塊中定義的 map 變數是全域的。由於 Nginx 會按檔名字母順序載入 conf.d/*.conf，若多個檔案定義相同名稱的 map 變數，後載入的會覆蓋前者。建議將所有 map 定義集中在 maps.conf。

Docker 掛載與唯讀權限 ​

什麼情況下會遇到這個問題：當希望確保容器內的設定檔不被意外竄改，或需要正確處理 log 寫入時。

在 compose.yaml 掛載設定檔時，建議使用 :ro（唯讀）標記：

yaml
volumes:
  - ./volumes/config/conf.d:/etc/nginx/conf.d:ro
  - ./volumes/logs:/var/log/nginx
  • :ro（唯讀）：適用於設定檔，防止容器內程序意外修改主機檔案。
  • 無 :ro：適用於 log 目錄、上傳目錄或快取目錄，因為 Nginx 必須具備寫入權限。

驗證與重新載入 ​

什麼情況下會遇到這個問題：當修改 Nginx 設定後，擔心語法錯誤導致服務崩潰。

請遵循以下標準流程：

  1. 測試語法：docker compose exec nginx nginx -t
  2. 重新載入：docker compose exec nginx nginx -s reload

使用 Template 處理環境變數 ​

什麼情況下會遇到這個問題：當需要根據不同環境（如開發、測試、正式）動態調整 Nginx 設定時。

Nginx 官方映像（1.19+）支援 Template 功能，將 .template 檔案放入 /etc/nginx/templates，容器啟動時會自動替換環境變數。

TIP

使用 Template 方式時，環境變數替換僅在容器啟動時執行。修改環境變數後，必須執行 docker compose up -d 重啟容器，無法透過 nginx -s reload 更新。

異動歷程 ​

  • 2025-11-27 初版文件建立。